home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / stdio / RCS / printf.man,v < prev    next >
Text File  |  1990-09-24  |  9KB  |  473 lines
  1. head     1.4;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.4
  10. date     90.09.24.14.38.57;  author kupfer;  state Exp;
  11. branches ;
  12. next     1.3;
  13.  
  14. 1.3
  15. date     89.10.24.08.58.43;  author ouster;  state Exp;
  16. branches ;
  17. next     1.2;
  18.  
  19. 1.2
  20. date     89.01.04.10.13.29;  author ouster;  state Exp;
  21. branches ;
  22. next     1.1;
  23.  
  24. 1.1
  25. date     89.01.04.10.13.03;  author ouster;  state Exp;
  26. branches ;
  27. next     ;
  28.  
  29.  
  30. desc
  31. @@
  32.  
  33.  
  34. 1.4
  35. log
  36. @Document vsnprintf.
  37. @
  38. text
  39. @.\"    @@(#)printf.3    6.5 (Berkeley) 6/5/88
  40. .\"
  41. .\" $Header$
  42. .TH PRINTF 3S "24 September 1990"
  43. .AT 3
  44. .SH NAME
  45. printf, fprintf, sprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion
  46. .SH SYNOPSIS
  47. .B #include <stdio.h>
  48. .PP
  49. .B printf(format
  50. .RB [ ,
  51. arg ] ...
  52. .B )
  53. .br
  54. .B char *format;
  55. .PP
  56. .B fprintf(stream, format
  57. .RB [ ,
  58. arg ] ...
  59. .B )
  60. .br
  61. .SM
  62. .B FILE
  63. .B *stream;
  64. .br
  65. .B char *format;
  66. .PP
  67. .B char *sprintf(s, format
  68. .RB [ ,
  69. arg ] ...
  70. .B )
  71. .br
  72. .B char *s, *format;
  73. .PP
  74. .B #include <varargs.h>
  75. .br
  76. .B vprintf(format, args)
  77. .br
  78. .B char *format;
  79. .br
  80. .B va_list args;
  81. .PP
  82. .B vfprintf(stream, format, args)
  83. .br
  84. .B FILE *stream;
  85. .br
  86. .B char *format;
  87. .br
  88. .B va_list args;
  89. .PP
  90. .B char *vsprintf(s, format, args)
  91. .br
  92. .B char *s, *format;
  93. .br
  94. .B va_list args;
  95. .PP
  96. .B char *vsnprintf(s, nBytes, format, args)
  97. .br
  98. .B char *s;
  99. .br
  100. .B int nBytes;
  101. .br
  102. .B char *format;
  103. .br
  104. .B va_list args;
  105. .SH DESCRIPTION
  106. .I Printf
  107. places output on the standard output stream
  108. .BR stdout .
  109. .I Fprintf
  110. places output on the named output
  111. .IR stream .
  112. .I Sprintf
  113. places `output' in the string
  114. .IR s ,
  115. followed by the character `\\0'.
  116. Alternate forms, in which the arguments have already been
  117. captured using the variable-length argument facilities of
  118. .IR varargs (3),
  119. are available under the names
  120. .IR vprintf ,
  121. .IR vfprintf ,
  122. .IR vsprintf ,
  123. and
  124. .IR vsnprintf .
  125. .RI ( Vsnprintf
  126. is like
  127. .IR vsprintf ,
  128. except that it takes an additional argument specifying the size of the
  129. character buffer
  130. .IR s .
  131. It is included for compatibility with the Carnegie Mellon CS library.)
  132. .PP
  133. Each of these functions converts, formats, and prints the arguments
  134. that come after the 
  135. .I format 
  136. argument.
  137. The 
  138. .I format
  139. argument controls this conversion process.
  140. It is a character string which contains two types of objects:
  141. plain characters, which are simply copied to the output stream,
  142. and conversion specifications, each of which causes conversion and printing
  143. of the next successive
  144. .IR arg .
  145. .PP
  146. Each conversion specification is introduced by the character
  147. .BR % .
  148. The remainder of the conversion specification includes
  149. in the following order
  150. .TP
  151. .B \(bu
  152. Zero or more of the following flags:
  153. .RS
  154. .TP
  155. .B \(bu
  156. a `#' character
  157. specifying that the value should be converted to an ``alternate form''.
  158. For 
  159. .BR c ,
  160. .BR d ,
  161. .BR s ,
  162. and
  163. .BR u ,
  164. conversions, this option has no effect.  For 
  165. .B o
  166. conversions, the precision of the number is increased to force the first
  167. character of the output string to a zero.  For 
  168. .BR x ( X )
  169. conversion, a non-zero result has the string 
  170. .BR 0x ( 0X )
  171. prepended to it.  For 
  172. .BR e ,
  173. .BR E ,
  174. .BR f ,
  175. .BR g ,
  176. and
  177. .BR G ,
  178. conversions, the result will always contain a decimal point, even if no
  179. digits follow the point (normally, a decimal point only appears in the
  180. results of those conversions if a digit follows the decimal point).  For
  181. .B g
  182. and
  183. .B G
  184. conversions, trailing zeros are not removed from the result as they
  185. would otherwise be;
  186. .TP
  187. .B \(bu
  188. a minus sign `\-' which specifies
  189. .I "left adjustment"
  190. of the converted value in the indicated field;
  191. .TP
  192. .B \(bu
  193. a `+' character specifying that there should always be
  194. a sign placed before the number when using signed conversions;
  195. .TP
  196. .B \(bu
  197. a space specifying that a blank should be left before a positive number
  198. during a signed conversion.  A `+' overrides a space if both are used;
  199. .TP
  200. .B \(bu
  201. a zero `0' character indicating that zero-padding should be used
  202. rather than blank-padding.  A `\-' overrides a `0' if both are used;
  203. .RE
  204. .TP
  205. .B \(bu
  206. an optional digit string specifying a
  207. .I "field width;"
  208. if the converted value has fewer characters than the field width
  209. it will be blank-padded on the left (or right,
  210. if the left-adjustment indicator has been given) to make up the field width
  211. (note that a leading zero is a flag,
  212. but an embedded zero is part of a field width);
  213. .TP
  214. .B \(bu
  215. an optional period, followed by
  216. an optional digit string giving a
  217. .I precision
  218. which specifies the number of digits to appear after the
  219. decimal point, for e- and f-conversion, or the maximum number of characters
  220. to be printed from a string; if the digit string is missing,
  221. the precision is treated as zero;
  222. .TP
  223. .B \(bu
  224. the character
  225. .B l
  226. specifying that a following
  227. .BR d ,
  228. .BR i ,
  229. .BR o ,
  230. .BR x ,
  231. or
  232. .B u
  233. corresponds to a long integer
  234. .IR arg ,
  235. or that a following
  236. .B n
  237. corresponds to a pointer to a long integer
  238. .IR arg ;
  239. .TP
  240. .B \(bu
  241. the character
  242. .B h
  243. specifying that a following
  244. .BR d ,
  245. .BR i ,
  246. .BR o ,
  247. .BR x ,
  248. or
  249. .B u
  250. corresponds to a short integer
  251. .IR arg ,
  252. or that a following
  253. .B n
  254. corresponds to a pointer to a short integer
  255. .IR arg ;
  256. .TP
  257. .B \(bu
  258. a character which indicates the type of
  259. conversion to be applied.
  260. .PP
  261. A field width or precision may be `*' instead of a digit string.
  262. In this case an integer
  263. .I arg
  264. supplies
  265. the field width or precision.
  266. .PP
  267. The conversion characters
  268. and their meanings are
  269. .TP
  270. .B dox
  271. The integer
  272. .I arg
  273. is converted to signed decimal, unsigned octal, or
  274. unsigned hexadecimal notation respectively.
  275. .TP
  276. .B i
  277. An alias for `d'.
  278. .TP
  279. .B f
  280. The float or double
  281. .I arg
  282. is converted to decimal notation
  283. in the style `[\fB\-\fR]ddd.ddd'
  284. where the number of d's after the decimal point
  285. is equal to the precision specification
  286. for the argument.
  287. If the precision
  288. is missing,
  289. 6 digits are given;
  290. if the precision is explicitly 0, no digits and
  291. no decimal point are printed.
  292. .TP
  293. .B eE
  294. The float or double
  295. .I arg
  296. is converted in the style
  297. `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd'
  298. where there is one digit before the decimal point and
  299. the number after is equal to the
  300. precision specification for the argument;
  301. when the precision is missing,
  302. 6 digits are produced.
  303. An uppercase E is used for `E' conversion.
  304. .TP
  305. .B gG
  306. The float or double
  307. .I arg
  308. is printed in style
  309. .B f
  310. or in style
  311. .B e
  312. .RB ( E )
  313. whichever gives full precision in minimum space.
  314. .TP
  315. .B c
  316. The character
  317. .I arg
  318. is printed.
  319. .TP
  320. .B s
  321. .I Arg
  322. is taken to be a string (character pointer)
  323. and characters from the string are printed until
  324. a null character or until
  325. the number of characters indicated by the precision
  326. specification is reached;
  327. however if the precision is 0 or missing
  328. all characters up to a null are printed.
  329. .TP
  330. .B u
  331. The unsigned integer
  332. .I arg
  333. is converted to decimal
  334. and printed (the result will be in the
  335. range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11
  336. and 65535 on a PDP-11).
  337. .TP
  338. .B n
  339. .I Arg
  340. is taken to be a pointer to an integer (possibly
  341. .B short
  342. or
  343. .BR long )
  344. through which is stored the number of characters written
  345. to the output stream (or string) so far by this call to
  346. .B printf
  347. (or
  348. .BR fprintf ,
  349. etc.).
  350. .TP
  351. .B p
  352. .I Arg
  353. is taken to be a pointer to
  354. .BR void ;
  355. it is printed in style
  356. .BR x .
  357. .TP
  358. .B %
  359. Print a `%'; no argument is converted.
  360. .PP
  361. In no case does a non-existent or small field width
  362. cause truncation of a field;
  363. padding takes place only if the specified field
  364. width exceeds the actual width.
  365. Characters generated by
  366. .I printf
  367. are printed as by 
  368. .IR putc (3S).
  369. .PP
  370. .SH "RETURN VALUE"
  371. Except for \fIsprintf\fR, \fIvsprintf\fR, and \fIvsnprintf\fR, 
  372. the functions all return
  373. the number of characters printed, or -1 if an error occurred.
  374. \fISprintf\fR, \fIvsprintf\fR, and \fIvsnprintf\fR return 
  375. a pointer to the result string (the first argument).
  376. .SH EXAMPLES
  377. .br
  378. To print a date and time in the form `Sunday, July 3, 10:02',
  379. where
  380. .I weekday
  381. and
  382. .I month
  383. are pointers to null-terminated strings:
  384. .RS
  385. .HP
  386. .nh
  387. printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
  388. .RE
  389. .hy
  390. .PP
  391. To print
  392. .if n pi
  393. .if t \(*p
  394. to 5 decimals:
  395. .IP
  396. printf("pi = %.5f", 4*atan(1.0));
  397. .SH "SEE ALSO"
  398. putc(3S), scanf(3S)
  399. .SH BUGS
  400. The functions still supports \fI%D\fP, \fI%O\fP, and \fI%U\fP.  Do not
  401. use these formats, as they will be disappearing soon.
  402. .PP
  403. For ANSI compatibility, the
  404. .I sprintf
  405. family should return the number of characters printed, rather than the
  406. buffer string.
  407. @
  408.  
  409.  
  410. 1.3
  411. log
  412. @Fix documentation for sprintf and vsprintf to correspond
  413. to reality.
  414. @
  415. text
  416. @d3 2
  417. a4 1
  418. .TH PRINTF 3S "October 22, 1987"
  419. d7 1
  420. a7 1
  421. printf, fprintf, sprintf, vprintf, vfprintf, vsprintf \- formatted output conversion
  422. d57 10
  423. d84 1
  424. d86 17
  425. a102 5
  426. .IR vsprintf .
  427. .PP
  428. Each of these functions converts, formats, and prints its arguments after
  429. the first under control of the first argument.
  430. The first argument is a character string which contains two types of objects:
  431. d106 1
  432. a106 2
  433. .I arg
  434. .IR printf .
  435. d333 2
  436. a334 1
  437. Except for \fIsprintf\fR and \fIvsprintf\fR, the functions all return
  438. d336 2
  439. a337 2
  440. \fISprintf\fR and \fIvsprintf\fR return a pointer to the result string
  441. (the first argument).
  442. d364 5
  443. @
  444.  
  445.  
  446. 1.2
  447. log
  448. @Added "v" forms to NAME section.
  449. @
  450. text
  451. @d28 1
  452. a28 1
  453. .B sprintf(s, format
  454. d51 1
  455. a51 1
  456. .B vsprintf(s, format, args)
  457. d310 1
  458. a310 1
  459. The functions all return
  460. d312 2
  461. @
  462.  
  463.  
  464. 1.1
  465. log
  466. @Initial revision
  467. @
  468. text
  469. @d6 1
  470. a6 1
  471. printf, fprintf, sprintf \- formatted output conversion
  472. @
  473.